/**
  ******************************************************************************
  * @file    fsm_event_processor.h
  * @author  ashuai0110
  * @version V2.4
  * @date    2024-09-10
  * @brief   有限状态机FSM(参考QP的FSM)
  *
  ******************************************************************************
  * @attention
  *
  * 版权声明:内容为编者(ashuai0110)原创,使用请注明出处,当然,你也可以不这样做^_^
  * 出处链接:https://gitee.com/ashuai0110/mcu_reuse_development_module.git
  *
  ******************************************************************************
  */

#ifndef __FSM_EVENT_PROCESSOR_H
#define __FSM_EVENT_PROCESSOR_H

#ifdef __cplusplus
extern "C" {
#endif

/* 包含头文件-----------------------------------------------------------------*/
#include "common_include.h"

/**
 * @addtogroup state_machine
 * @{
 */

/**
 * @addtogroup fsm_event_processor
 * @{
 */

/* 宏定义---------------------------------------------------------------------*/
/**
 * @defgroup fsm_global_macros fsm global macros
 * @{
 */

/**
 * @defgroup fsm_signal fsm signal
 * @{
 */
#define FSM_SIG_EMPTY                           (0u) /*!< 空信号(不使用) */
#define FSM_SIG_ENTRY                           (1u) /*!< 进入信号(进入某状态时触发一次) */
#define FSM_SIG_EXIT                            (2u) /*!< 退出信号(退出某状态时触发一次) */
#define FSM_SIG_INIT                            (3u) /*!< 初始化信号 */
#define FSM_SIG_USER                            (4u) /*!< 用户信号(用户自定义信号从此开始递增) */
/**
 * @}
 */

/**
 * @defgroup fsm_ret_value fsm return value
 * @{
 */
#define FSM_RET_HANDLED                         (0u) /*!< 信号进行过处理则返回 */
#define FSM_RET_IGNORED                         (1u) /*!< 信号未进行过处理则返回 */
#define FSM_RET_TRAN                            (2u) /*!< 信号进行过处理且状态需要转换则返回 */
/**
 * @}
 */

/**
 * @defgroup fsm_ret_fun fsm return function
 * @{
 */
#define FSM_HANDLED()                           (FSM_RET_HANDLED)
#define FSM_IGNORED()                           (FSM_RET_IGNORED)
/* 切勿在FSM_SIG_ENTRY和FSM_SIG_EXIT里返回FSM_TRAN() */
#define FSM_TRAN(target)                        (((fsm_t *)_fsm)->stateHandler = (fsm_state_handler_t)(target), FSM_RET_TRAN)
/**
 * @}
 */

/**
 * @}
 */

/* 类型定义-------------------------------------------------------------------*/
/**
 * @defgroup fsm_global_types fsm global types
 * @{
 */

/**
  * @brief  FSM事件 structrue definition
  */
typedef struct fsm_event {
    uint16_t signal; /*!< 事件信号 */
} fsm_event_t;

/**
  * @brief  FSM状态处理函数
  *
  * @param  _fsm            : FSM实例化对象
  *
  * @param  event           : FSM事件
  *
  * @retval 返回处理状态 @ref fsm_ret_value
  *    @arg FSM_RET_HANDLED : 已处理
  *    @arg FSM_RET_IGNORED : 忽视
  *    @arg FSM_RET_TRAN    : 状态被转换
  */
typedef uint8_t (* fsm_state_handler_t)(void *_fsm, fsm_event_t const *event);

/**
  * @brief  FSM处理器 structrue definition
  */
typedef struct fsm {
    fsm_state_handler_t stateHandler; /*!< 状态处理函数 */
} fsm_t;

/**
 * @}
 */

/* 全局变量-------------------------------------------------------------------*/

/* 函数原型-------------------------------------------------------------------*/
/**
 * @addtogroup fsm_global_functions
 * @{
 */

void fsm_ctor(fsm_t *_fsm, fsm_state_handler_t initFn);

void fsm_init(fsm_t *_fsm, fsm_event_t const *event);

void fsm_dispatch(fsm_t *_fsm, fsm_event_t const *event);

/**
 * @}
 */

/**
 * @}
 */

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* fsm_event_processor.h */
